home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Ian & Stuart's Australian Mac: Not for Sale
/
Another.not.for.sale (Australia).iso
/
fade into you
/
being there
/
Issues & Ideas
/
SGML
/
Kimber-on-HyQ-1.1
< prev
next >
Wrap
Text File
|
1992-07-21
|
91KB
|
2,798 lines
Sender: drmacro@vnet.ibm.com
Message-Id: <9308030227.AA01688@relay1.UU.NET>
Date: Mon, 2 Aug 93 22:27:36 EDT
From: "W. Eliot Kimber" <drmacro@vnet.ibm.com>
To: srn@techno.com
HYTIME AND SGML
UNDERSTANDING THE
HYTIME HYQ QUERY
LANGUAGE
1.1
August 2, 1993
W. Eliot Kimber
VNET: DRMACRO at RALVM13
Internet: drmacro@vnet.ibm.com
IBMMAIL: USIB2DK9@IBMMAIL
Phone: (919) 254-5160
Mail:
IBM Corporation
4205 S. Miami Blvd.
Research Triangle Park, NC 27709 USA
Mail stop: E14/B500
IBM Internal Use Only
FIRST EDITION
You may copy this document freely as long as this copyright notice is
included without modification.
(C) COPYRIGHT INTERNATIONAL BUSINESS MACHINES CORPORATION 1993. ALL
RIGHTS RESERVED.
Note to U.S. Government Users -- Documentation related to restricted
rights -- Use, duplication or disclosure is subject to restrictions
set forth in GSA ADP Schedule Contract with IBM Corp.
------------------------------------------------------------------------------
About this Document
This document is intended to provide a brief, tutorial introduction to
the HyQ language. It is assumed you have a working knowledge of SGML
and have a copy of the HyTime standard, ISO 10744 at hand, although it
does not assume you have more than a passing familiarity with HyTime.
-----------
Conventions
Whenever a term defined in either the SGML standard, ISO 8879, or the
HyTime standard is used for the first time, it is highlighted like so:
SPECIALIZED TERM. These terms represent the specialized jargon of
SGML and HyTime. They have precise meanings that may be different
from their more common usage.
The HyQ functions are defined using "railroad track" syntax diagrams
similar to the sort used in Pascal documentation. To read a syntax
diagram, start at the left and follow the tracks, collecting
characters as you go, including any blanks. A typical diagram looks
like this:
.- DEFAULT-.
>>--fubar(variable--.-----------.--.- CHOICE1-.--+----------+-------->
'- OPTIONAL-' '- CHOICE2-' |- CHOICE1-|
'- CHOICE2-'
<-----------<
>--| Fragment Reference |--- REPEATABLE-----------------------------><
Fragment references are references to other syntax diagrams presented
elsewhere.
-----------------------------
Assumptions Made for Examples
To keep the examples as brief as possible, not all the aspects of
HyTime that you would have in a real application are shown. For
example, elements that are defined for the purpose of the examples are
not explicitly defined anywhere. All elements used in examples that
are HyTime elements are presented as is. Elements that are made-up
application-specific elements for the purposes of the examples are
always indicated as being made-up.
------------------------
Accuracy of the Examples
I have made every effort to check the examples against the HyTime
standard. Wherever I have had a question as to the proper
specification or use of a HyTime or HyQ construct I have asked for
clarification from Charles Goldfarb, the editor of the HyTime
standard, or Steve DeRose, one of the principle architects of the HyQ
language itself. Any inaccuracies are mine. If you find any
inaccuracies, or have any other comments on this document, please send
a note to the address shown on the title page.
------------------------------------------------------------------------------
Acknowledgements
Special thanks to the following people who have provided invaluable
assistance in insuring the quality and accuracy of this information:
o Victoria Newcomb
o Neill Kipp
o Steve DeRose
o Michael Sperberg-McQueen
o Wayne Wohler
o David Cattarin
------------------------------------------------------------------------------
Changes to This Document
| Changes to the latest version are marked with a vertical bar in the
| margin as this paragraph is.
Changes for version 1.1, August 2, 1993:
o Fixed several errors in detail in various examples
o Fixed the TESTDOC example by adding missing ID= values and
explicitly ending all elements.
o Added to the description of property locations and fixed all the
Proploc() examples to match ISO 10744.
o Fixed technical errors in the description of Dataloc().
o Clarified the description of Listloc().
------------------------------------------------------------------------------
Introduction to HyTime and HyQ
HyTime is an ISO standard that defines an architecture for creating
hypertext and hypermedia applications. HyTime primarily addresses the
problem of hyperlinking as a problem of addressing, in other words,
locating objects in space or time. A key aspect of addressing is the
use of queries to find things based on their properties.
HyTime is an SGML application, which means that it is designed using
SGML as the notation language and defines a number of functions
related directly to SGML constructs. The HyTime standard defines the
HyQ query language as the recommended notation to use for queries
within a HyTime context. HyQ is designed to directly reflect HyTime
constructs and addressing methods and is therefore optimized for use
within HyTime applications. HyQ is not tied to any particular
retrieval or search engine and therefore represents an interchange
language for queries that would then be interpreted into concrete
queries using proprietary query languages or mechanisms.
This document is an introduction to the HyQ language. It shows how
the HyQ language is structured and how you use it to construct various
types of queries. It also provides an overview of the various HyTime
addressing methods, as those are also used by HyQ.
The last part of this document is a HyQ reference, containing a
reference page for each HyQ function. This reference is intended to
supplement the HyQ definition in the HyTime standard itself by
providing examples and explanations of typical uses of each function.
------------------------------------------------------------------------------
HyTime Addressing and HyQ
HyTime is about addressing. HyTime works with objects in finite
coordinate spaces and objects within trees.
---------------------
Coordinate Addressing
Coordinate spaces are always defined in terms of quanta, in other
words, non-divisible integer units. A one-dimensional coordinate
space can be represented as a number line, like so:
1 2 3 4 5 6 7 8
| | | | | | | | |
|---+---+---+---+---+---+---+---+
| | | | | | | | |
This coordinate space consists of eight quanta. A two-dimensional
coordinate space can be represented by a matrix:
+-----------------------------------------------+
5 | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---|
4 | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---|
3 | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---|
2 | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---|
1 | | | | | | | | | | | | |
+-----------------------------------------------+
1 2 3 4 5 6 7 8 9 10 11 12
Locations within coordinate spaces are represented by sets of
DIMENSION SPECIFICATIONS. A dimension specification, or dimspec, is
made up of two AXIS MARKERS, which are signed, non-zero integers. The
first axis marker locates the starting quantum and the second axis
marker defines the extent (number of quanta) of the address. The
start is the start of the location and is normally the quantum number
of the starting position. The extent is the number of quanta to move
to define the length of the location on that axis. Counting is always
done in the direction of the end of the finite coordinate space
(except in one special case explained below).
For example, the dimension specification '1 1' indicates the first
quantum, '2 1' locates the second quantum, and '2 3' locates the
second through fourth quanta (start at quantum 2 and move over three
quanta). A single dimension specification locates within a
one-dimensional coordinate space.
When multiple axis marker pairs are used to address multiple locations
as though they were a single object, they are contained in a DIMENSION
LIST or dimlist. The marker pairs within a given dimension list all
apply to a single axis in the addressible range. You can think of a
dimspec as a special case of dimlist that only addresses a single
location.
| Dimension specifications are used to locate within a single dimension
| or along a single axis. but to locate within a multi-dimensional
| space, you create an extent, which contains a dimlist for each axis in
| the coordinate space and defines the extent of the region of the
| finite coordinate space being located.(1) To locate the first quantum
| in a matrix, you would specify '1 1' '1 1'. To locate a rectangular
| area two quanta by three quanta, you would specify the extent like so:
| <extent>
| <dimlist>1 2</><dimlist>1 3</>
| </extent>
| which would look like so:
+---------------------------------------------------+
6 | | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---+---|
5 | | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---+---|
4 | | | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---+---|
3 | x | x | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---+---|
2 | x | x | | | | | | | | | | | |
|---+---+---+---+---+---+---+---+---+---+---+---+---|
1 | x | x | | | | | | | | | | | |
+---------------------------------------------------+
1 2 3 4 5 6 7 8 9 10 11 12 13
extent="(1 2) (1 3)"
The area within a given coordinate space that a dimension
specification is actually addressing is called the ADDRESSABLE RANGE.
The addressable range always has well-defined boundaries, in other
words, a start and an end. Knowing where the end of the addressable
range is lets you specify locations relative to the end of the range
as well as relative to the start of the range.
The start and extent values have special meanings when a minus sign is
used with them.
When the start quantum is negative, it indicates that counting starts
at the end of the addressable range rather than at the beginning. For
example, the dimspec '-1 1' locates the last quantum in the range,
| while '-2 2' locates the last two quanta in the range.
When the extent value is negative, it indicates that the extent is
from the end of the range, not the starting quanta. For example, the
dimspec '1 -1' locates the entire range, while '2 -1 'locates all but
the first quanta in the range. '2 -2' would locate all but the first
and last quanta in the range.
When the first marker is negative and the extent is negative, it
indicates that the direction of counting is from the end of the range,
but starting from the second marker, not the end of the range. In
other words, the first marker indicates the number of quanta to move
toward the start of the range, starting at the position indicated by
the second marker. For example, in a range of ten quanta, the dimspec
'-3 -2' means the 7th through 9th quanta inclusive. In other words,
locate the second quanta from the end of the marker (quantum nine)
then locate the third quanta in the direction of the start of the
range (quantum seven):
Dimspec="-3 -2"
+--- Second quanta from end (-2)
V
1 2 3 4 5 6 7 8 9 10
| | | | | | | x | x | x | |
|---+---+---+---+---+---+---+---+---+---|
| | | | | | | A | | | |
+---- Third quanta from second marker (-3)
All this does is treat the end of the range as though it were the
start and the first marker as though it were the extent and the second
marker as though it were the starting quantum.
| Another way to think of this is that when the signs of both markers
| are the same, then the first indicates a start location and the second
| indicates the number of quanta to move to the right (moving right -2
| is the same as moving left 2).
----------------------------
Nodelist and Tree Addressing
HyTime also provides location mechanisms for locating objects within
trees. In HyTime terms, a tree represents a hierarchical collection
of NODES, where a node is to a tree what a quantum is to a coordinate
space: simply a way of defining where something is located in a tree.
Nodes can also be organized into lists, called NODE LISTS. Nodes have
the special property that they can be the roots of trees.
The typical use of tree locations in HyTime applications is to locate
elements within SGML documents, as SGML documents are always
hierarchical structures of elements and are therefore naturally
represented as trees(2). Other types of data can be addressed as
trees or nodelists by providing notation handlers for those data
notations that can translate node and tree addresses into real
addresses for that data type. For example, a notation handler for
PostScript data could allow addressing of pages in a PostScript
listing as nodes in a node list. It is up to the implementer of a
given HyTime system to provide this sort of functionality.
Nodes can thus be organized or viewed as members of node lists or
trees. Nodes can be located by any one of the following location
mechanisms:
o Tree location address
o list location address
o path location address
o relative location address
Node and tree locations are primarily used to locate elements within
SGML documents, but they can be used to locate within any type of data
that is represented as a tree or node list.
tree location address
Locates a node in a tree by selecting an ancestor node at each level
| of the tree. E.g., the location '1 2 3 1' selects the first child of
the third child of the second child of the root. Note that nodes are
counted in left-list preorder, e.g., top to bottom, left to right.
| Note also that the root node must always be identified in the tree
| location.
list location address
Address one or more nodes within a node list. The list location is a
coordinate location where the coordinate space is a list of nodes.
For example, the list location '2 3' locates the second through fourth
nodes in a node list.
path location address
Locates one or more "paths" down a tree. The path location address is
a coordinate location that addresses a tree as though it were a matrix
in which the rows are the levels of the tree and the matrix columns
are the paths down the tree.
Consider the following tree:
+---+
| A |
+---+
+----------+------------+
| | |
+---+ +---+ +---+
| B | | C | | D |
+---+ +---+ +---+
+-------+ | +-------+
| | | | |
+---+ +---+ +---+ +---+ +---+
| E | | F | | G | | H | | I |
+---+ +---+ +---+ +---+ +---+
|
+---+
| J |
+---+
All the paths through the tree can be represented as a matrix where
each column is a path from the root to a leaf:
Paths
1 2 3 4 5
---------
Level 1: A A A A A
Level 2: B B C D D
Level 3: E F G H I
Level 4: - J - - -
Any single path can be located by specifying the column and then the
number of nodes within the column to select. For example, the path
from A to J would be '2 1 1 -1'. The first dimension, '2 1', locates
the second column. The second dimension locates the entire length of
the column.
relative location address
Addresses nodes in a tree based on their genealogical relationship to
another node in the tree. You locate the position of the node the
other nodes are relatives of, specify the general relationship that
the target nodes have (e.g., child, ancestor, elder sibling, younger
sibling, descendant). The relationship specification effectively
defines the node list or pathlist within which the target nodes are
located. You then specify a coordinate location locating the actual
nodes. For example, to locate the third child of the root of a
document you would specify this relative location address:
<relloc id=sample-relloc
relation=children>3 1</relloc>
The root of the relative location is, by default, the root of the
document. The relation 'children' defines the target domain as the
node list consisting of all direct children of the root. The
dimension specification '3 1' locates the third node within the node
list, effectively locating the third child of the root.
------------------
Semantic Locations
Semantic locations provide means of locating aspects of objects that
are unique to their semantic roles, as opposed to their structural
roles. Semantic location methods are:
o Property locations (proploc). Proploc locates values of object
properties, such as attribute values and generic identifiers.
Non-SGML data notations can have properties defined for them using
the HyTime property definition constructs.
o Notation-specific locations (notloc). Notloc locates into data in
a given notation using addressing methods specific to that
notation, as opposed to using normal HyTime addressing that is
interpreted by a notation processor that understands HyTime
addressing.
o Bibliographic locations (bibloc). Bibloc locates elements that
are not directly addressable by the system, normally references to
real objects, such as printed books, people, and the like.
Proploc is the semantic location method used most often. Notloc is a
sort of "escape" that allows addressing into data notations for which
generalized HyTime support has not been provided.
Property Location Addressing
SGML elements have properties as defined by ISO 8879, e.g., the
generic identifier and any declared attributes. In addition,
application designers may define other properties for elements or for
other data types. Property definition is done in HyTime using the
HyTime property definition element form, defined in Annex A.2. You
can define new properties and given them names by which they can be
referred to from a proploc.
To refer to element attributes within a proploc, you specify the
property name 'ATTVAL' followed by the attribute name, separated by a
null end tag (NET) delimiter (normally a solidus ([], like so:
<HyQ>
proploc(DOMROOT ATTVAL[SECURITY])
</HyQ>
| The string ATTVAL[SECURITY]' is a qualified property name (qpn), made
| up of the following parts:(3) 'ATTVAL' identifies the property itself,
| in this case, an attribute value. '[SECURITY]' defines the specifier
| for the property, in this case, the attribute name. A specifier
| defines the data that allows for selection among properties of the
| same type. In this example, the attribute name is the specifier for
| selecting among the values of the various attributes of the element
| being located. Without the specifier, the proploc() would return the
| values of all the attributes. The syntax of qualified property names
| of this form is defined in section A.1.3 Useful Hylex Types in ISO
| 10744.
| All property names are specified relative to a defined set of
| properties, called a property set. For all standard SGML and HyTime
| constructs, these properties are part of the standard property sets
| used by default. However, you can specify the property set name
| explicitly, like so:
| <HyQ>
| proploc(DOMROOT HTsem1+ATTVAL[SECURITY])
| </HyQ>
| 'HTsem1' identifies the property set in which the named property is
| defined. The standard property sets are defined in section A.2.1 of
| ISO 10744.
Thus the proploc() function in this example returns the value of the
attribute. If the actual markup is:
<mydoc security="iuo">
Then the query would return the value 'iuo'.
The special keyword GI refers to the generic identifier property of
the element. Applied to the markup above, the following query returns
'mydoc'.(4)
<HyQ>
proploc(DOMROOT GI)
</HyQ>
| If you are going to need to specify the same long qualified property
| name many times, it may be convenient to define a property name
| synonym for it. For example, the value of the ID= attribute is a
| property that is use frequently, so it would make sense to define a
| synonym for it, something like this:
| <HyPD psn=myprops syn pn=idatt>
| HTsem1+ATTVAL[ID]
| </HyPD>
| The property set name 'myprops' must be declared as a notation and
| represents a set of properties defined locally (for example, within
| the metadtd for an application architecture or the concrete DTD of an
| SGML application). Having defined this synonym, you can now use the
| property name directly and simply:
| proploc(CAND myprops+idatt)
| You can also specify property set names on elements that contain the
| query using the qpnpsn= attribute (defined as one of the all-qual
| qualifying name attributes in section 6.7.3 of ISO 10744). This
| allows you to specify the names of property sets to be searched to
| find the definitions of various property names, eliminating the need
| to explicitly specify property set names. For example, the above
| proploc() could be changed to this, within the context of a HyQ
| element:
| <HyQ qpnpsn=myprops>
| proploc(CAND idatt)
| </hyq>
Notation Location Addressing
Notation locations are location address specifications unique to a
particular data notation, rather than being standard HyTime dimension
references or queries. Notation locations must be used to address
into data notations for which a HyTime-knowledgeable notation
processor is not available.
The main problem with notation locations is that they are directly
tied a specific notation and are thus not very interchangeable.
In a pure HyTime system, for each supported notation there would be at
least one notation processor that would accept standard HyTime address
(dimension specifications or data locations, for example) and would
know how to transform the HyTime specification into real locations in
the specific data notation. For example, say you wanted to address
words in text regardless of the format that text is stored in, because
it could be in any one of several proprietary formats. If each format
has a HyTime notation processor available, you could use a simple data
location address with a defined quanta of WORD without having to worry
about how to actually find words in the actual data, because the
notation processor would handle that transparently.
However, if there was a format for which there was no
HyTime-knowledgeable notation processor, to address words, you might
have to specify the address in the specific notation. For text in a
given word processor format, that might mean specifying the editor
macros that would return what you want as the address, say something
like this:
<notloc notation=PandaWord>
@macro(find_mark("fubar"), start_select(), move_word(3), end_select(),
copy(), return(clipboard()))
</notloc>
Compare with the equivalent dataloc:
<dataloc locsrc=fubar quantum=word>1 3</dataloc>
HyQ does not provide a notation location function, but you could use a
notloc indirectly by using the object-of function (oo()) to refer to
the notloc element that addresses the objects you need.
Bibliographic Location Addressing
Bibliographic locations address objects that are not directly
addressable by the computer system or application. For example, you
could create a "hyperlink" to a document that only exists in print by
using a bibliographic location giving its Library of Congress number.
Bibliographic locations cannot be used as location sources, so they
cannot be used within HyQ queries.
------------------------------------------------------------------------------
Getting Started with HyQ
HyQ is a language for use with HyTime location addressing facilities.
It represents a sort of "API" by which computer systems can interact
with HyTime systems using HyTime location mechanisms. For example, a
database retrieval system might use HyQ queries to locate data within
an SGML database, or an online presentation system might use HyQ
queries to interact with other online systems through a HyTime engine.
HyQ queries can also be used within HyTime location elements that
allow queries, such as the NMQuery element used within named address
location elements (nameloc). The HyQ language is defined within Annex
A of the HyTime Standard.
----------
HyQ Basics
HyQ operates on and returns node lists. The set of nodes against
which the query is performed is called the QUERY DOMAIN. This query
domain is defined by specifying the node that forms the root of the
tree containing the target nodes. For example, to locate elements
within an SGML document, you would specify the root node of the
document (the DOCUMENT ELEMENT) as the domain root.
The HyQ language itself is a lisp-like language where queries are
specified by nesting HyQ functions within other functions. A typical
HyQ query is:
<HyQ qdomain=mydocument>
| Select(DOMTREE EQ(Proploc(CAND GI) "CHAPTER"))
</HyQ>
The HyQ element contains the query itself; the qdomain= attribute
identifies the query domain (the root node of the tree against which
the query is performed). In this example, pointing to the document
element for an document called mydocument. By default, the query
domain for a HyQ query is the current SGML document.
Function parameters are blank-delimited, with literal strings enclosed
in single or double quotes. A query can include variable arguments
that are passed in as values of the ARGS= attribute of the HyQ
element.
The following keywords have special meaning within a HyQ query:
DOMROOT Refers to the root node list of the query.
DOMTREE Refers to the tree of nodes rooted at DOMROOT.
CAND Refers to the candidate under test in a select() function.
The select() function takes a node list and an assertion and
applies the assertion to each member of the node list in turn.
The keyword CAND can be used within the assertion to refer to
the current candidate node. The select() function returns a
node list containing the candidates for which the assertion
was true.
For example, in the HyQ query shown above, the select's input node
list is defined as the DOMTREE, in other words, all nodes in the query
domain. The assertion is asking if the candidate's GI value (tag
name) is equal to the value 'Chapter'. The select then returns a
nodelist containing each node that does have a GI of 'Chapter'. In
the context of this query, the nodes are SGML elements.
The essential question in this query is "is the GI equal to
'Chapter'?" To answer this question, you must first find out for each
node in the query domain what its GI is, thus the proploc() function,
which returns the value of a property, in this case, the GI property:
"Proploc(CAND GI)". Remember that the CAND keyword refers to the
current candidate node from the node list specified for the select()
function.
Having the GI for each candidate node, you now compare it to the
literal string 'Chapter' using the EQ() function. The EQ() function
compares the first parameter and the second parameter and returns TRUE
if they are equal. This true or false value is then used by the
select() function to determine which of the nodes in the input node
list to return.
To test this query, try applying it to the following sample document:
<testdoc id=a>
<body id=b>
<Chapter id=intro-chap><title id=e>Introduction</title>
<p id=c>Introduction</p>
<Chapter id=complex><title id=f>Complex Stuff</title>
<p id=d>This is about complex stuff.</p>
</body>
</testdoc>
The outermost function is:
select(DOMTREE assertion)
The keyword DOMTREE represents the node list of all elements in the
document, rooted at the document element (<testdoc> in this case).
For this exercise, represent this node list by listing the IDs of the
elements:
| "a b intro-chap e c complex f d"
The assertion is then applied to each member of the node list.
To work the assertion, start from the inside out. The lowest level
function returns the GI of each candidate node using the proploc()
function:
proploc(CAND GI)
For the first node in node list (element with ID=a), proploc returns
'testdoc'.
The next layer is the EQ() function to see if the GI is equal to the
string 'Chapter':
EQ(CAND proploc(CAND GI) "CHAPTER")
For the first candidate (taken from the node list supplied for the
select), the element with ID=a, the result of the EQ is FALSE because
'testdoc' is not equal to 'Chapter'. Thus, the candidate is not put
into the node list returned by the select() function.
Repeat the above steps for each node in the node list. The node list
returned by the select() should be:
"intro-chap complex"
Note that for this example you've used the IDs of the elements to
represent the node list. In a real system, the node list would
actually contain pointers to the SGML elements themselves, rather than
a literal list of element IDs. This is an important distinction to
keep in mind because a node list can be a set of literal values. For
example, consider this query:
<HyQ>
proploc(DOMTREE ATTVAL[ID])
</HyQ>
This query uses the proploc() function to return for each node in
DOMTREE the value of the ID= attribute, resulting in a node list that
is a set of literal ID values.
It is important to keep in mind the type of data each HyQ function
| returns. HyQ functions return one of three types of data: Boolean
| values (true or false), node lists, or literal data. All the
| assertion functions return Boolean values. Dataloc() and proploc()
| return literal data, and all other functions return node lists. Note
| that literal data strings can be the nodes in a node list. For
| example, a proploc() that operates against each of the nodes in a node
| list will itself return a node list of literal values, one for the
| property value for each node in the input node list.
These are simple examples, but they demonstrate the basic approach to
using HyQ to locate objects and get information about objects.
----------------------
Defining HyQ Functions
You can define HyQ functions to capture common queries that can be
re-used. To create a HyQ function, you create a HyQ element with an
FN= attribute. The FN= attribute defines the function name for this
function:
<HyQ fn=HasGI><!-- Returns elements in DOMTREE with specified GI -->
Select(DOMTREE EQ(proploc(CAND GI) %1))
</HyQ>
The '%1' is a variable parameter.
You use a function one of two ways. You can refer to a function
directly from the HyQ element by using the UseFN= and Args= attributes
to refer to a previously-defined function:
<HyQ usefn=HasGI args="P"><!-- Find all elements with GI 'P' -->
When you specify the UseFN= attribute, the HyQ element is empty and
cannot have an end tag specified.
You can also use a function within another HyQ query using the UseQ()
function to name the function and pass the arguments:
<HyQ>
UseQ(HasGI "P")
</HyQ>
The parameters are substituted in the order specified on the Args=
attribute or in the UseQ() function. Parameters for which no value
was specified are empty.
------------------------------------------------------------------------------
The HyQ Primitive Operations
This section defines each of the HyQ primitive functions. The
description of each function contains a formal definition of its
parameters, a general description of what the function does, and some
examples of how it might be used.
This information is taken directly from Annex A of ISO 10744.
The functions are in alphabetical order by function name. The
following entries group the various related funcions together:
NODE Lists the constructs that are valid wherever a node is
valid.
NODE LIST Lists the constructs that are valid wherever a node list is
valid.
ASSERTION Lists the functions that provide Boolean operations or
logical comparisons.
NLOPS Lists functions that operate against node lists
NLDEFS Lists functions that define or create node lists
------------------------------------------------------------------------------
ah()
User-defined assertion handler
Syntax
>>--ah(idref -| Node List |-)---------------------------------------><
idref
Refers to the object that implements the assertion.
NODE LIST
The node list contains the operands of the assertion. The meaning
of the operands is defined by the assertion implementation.
Purpose
The assertion handler function allows you to define and implement
assertions that the base HyQ definition does not provide.
Examples
In the following example, the ID reference is to an
application-defined element that contains a Rexx function that
implements the assertion.
<assertion-function id=compare-objects>
/* Rexx Function */
Compare_Objects:
procedure
arg objectname fieldname comparison_value .
interpret "IF "objectname"."fieldname "== comparison_value ",
"THEN return(1) ELSE return(0)"
return(0) /* just in case */
</assertion-function>
.
.
.
<HyQ>
select(DOMTREE ah(compare-objects ("mystem" "0owner" "DRMACRO")))
</HyQ>
In this example, the DOMTREE would be defined to be the set of Rexx
stemmed variables the assertion is applied against. The node list of
parameters for the Compare_Objects() Rexx function results in the
following IF statement being executed as a result of applying the
interpret operation:
IF mystem.0owner == comparison_value
THEN return(1) ELSE return(0)
The Rexx variable comparison_value has the value 'DRMACRO' in this
case.
------------------------------------------------------------------------------
and()
Test Boolean AND
Syntax
<---------------<
>>--and(---| Assertion |---)----------------------------------------><
ASSERTION
Any of the HyQ assertion functions.
Purpose
And() returns TRUE only when all assertions return TRUE.
Examples
In this example, And() is used to see if two properties have a certain
combination of values:
<HyQ>
select(DOMTREE AND(EQ(proploc(CAND ATTVAL[STATUS]) "CHANGED")
EQ(proploc(CAND ATTVAL[VERSION]) "V1R2")))
</HyQ>
The AND() in this case contains two EQ() assertions. Each EQ()
compares the value of an attribute with a string and returns TRUE or
FALSE based on the match. The AND() function will return TRUE if both
EQ() functions return TRUE, otherwise it will return FALSE.
Thus the select() function will return a node list containing each
element in DOMTREE for which STATUS equals 'CHANGED' and VERSION
equals 'V1R2'.
------------------------------------------------------------------------------
assert()
Test assertion
Syntax
>>--assert(-.-TRUE----------.-)-------------------------------------><
|-FALSE---------|
'-| Assertion |-'
TRUE
FALSE
ASSERTION
The Boolean value to assert (TRUE or FALSE) or an assertion
function that will return either TRUE or FALSE.
Purpose
Returns TRUE or FALSE.
Examples
In this trivial example, the Assert() function causes the select()
function to always return the input node list:
<HyQ>
select(DOMTREE assert(TRUE))
</HyQ>
------------------------------------------------------------------------------
assertion
Functions that return TRUE or FALSE
Syntax
ASSERTION:
|--assert(-.-| assert() |--.-)---------------------------------------|
|-| ah() |------|
|-| compare() |-|
|-| ordered() |-|
|-| and() |-----|
|-| or() |------|
|-| not() |-----|
|-| forall() |--|
'-| exists |----'
Purpose
All the assertion functions return TRUE or FALSE. Use assertion
functions within select() or within any function that takes an
assertion as an argument.
Note that exists is not a function, but is merely a property of node
lists such that when a node or node list occurs where an assertion is
expected, the node evaluates to TRUE if it is non-empty, FALSE if it
is empty.
| For example, the following And() function returns TRUE because
| assign() always returns true and the node list referenced by nlref()
| is not empty (having been assigned a non-null value):
| <HyQ>
| and(assign(notempty ("has a value"))
| nlref(notempty)
| )
| </HyQ>
------------------------------------------------------------------------------
assign()
Assign a local name to a node list
Syntax
>>--assign(name -| Node List |-)------------------------------------><
name
The symbolic name to be assigned to the node list. The name is
available to the entire HyQ query body and any nested queries.
The name cannot be re-defined within the scope of a single query.
NODE LIST
The node list to which the name is being assigned.
Purpose
Use Assign() to assign a symbolic name to a node list as a convenience
in specifying other parts of a query. Use the nlref() function to use
a node list name created with assign().
Examples
In this example, assign() is used to assign a name to the node list
representing the elder siblings of a node:
<HyQ>
ASSIGN(ElderSiblings relloc(DOMTREE oo(an-element) esib (1 -1)))
select(nlref(ElderSiblings) EQ(proploc(CAND GI) "P"))
</HyQ>
The relloc() function defines the node list by locating all elder
siblings of the element with the ID of 'an-element'. This named node
list is then used in the select() function to return the list of
elements within the list of elder siblings that have a GI of 'P'.
------------------------------------------------------------------------------
count()
Return number of quanta in range
Syntax
>>--count(-| Node List |--.----------.-)----------------------------><
'- quantum-'
Purpose
Examples
This example extends the example for assign by using Count() to return
the number of elder P siblings of the element with the ID
'an-element':
<HyQ>
assign(ElderSiblings relloc(DOMTREE oo(an-element) esib (1 -1)))
COUNT(select(nlref(ElderSiblings) EQ(proploc(CAND GI) "P")))
</HyQ>
------------------------------------------------------------------------------
compare()
Tests ordering of nodes in lists
Syntax
.- STR--. <- --------------------<
>>--compare(--.-EQ-.--(--+-------+----.-| Node |------.--)----------><
|-NE-| |- NORM-| '-| Node List |-'
|-LT-| |- WORD-|
|-LE-| |- NAME-|
|-GT-| |- SINT-|
|-GE-| |- DATE-|
|-SS-| |- TIME-|
|-NS-| '- UTC--'
|-ST-|
|-SE-|
|-BT-|
|-BE-|
|-HO-|
|-HE-|
|-IH-|
'-IE-'
comparison operator
Defines the type of comparison to be performed.
COMPARISON OPERATORS
The following comparison operators can be used to specify the type
of comparison to perform against the members of the node list:
EQ
All members are equal to each other.
NE
AT least two operands are not equal.
LT
Each operand is less than its successor.
LE
Each operand is less than or equal to its successor.
GT
Each operand is greater than its successor.
GE
Each operand is greater than or equal to its successor.
SS
All operands are the same size (same number of quanta)
NS
At least two operands are not the same size.
ST
Each operand is smaller (shorter) than its successor.
SE
Each operand is smaller (shorter) than or equal to its
successor.
BT
Each operand is bigger (longer) than its successor.
BE
Each operand is bigger (longer) than or equal to its
successor.
HO
Each operand holds its successor (proper superstring)
HE
Each operand holds or equals its successor (superstring)
IH
Each operand is held by its successor (proper substring)
IE
Each operand is held by or equals its successor (substring)
QUANTUM
Represents the Quantum= attribute of the dataloc form. This value
defines what constitutes a quantum in the data. Valid values are:
NORM
Normalized text: all characters except record start (RS),
record end (RE), and separation characters (SEPCHAR), normally
space and tab.
WORD
Word tokens: all name characters.
NAME
SGML name: NAME constructed according to ISO 8879.
SINT
Signed integer: digit string, optionally preceded by a hyphen
or plus.
DATE
UTC date: valid date in UTC yyy-mm-dd format.
TIME
UTC time: valid time in UTC hh:mm:ss.decimal format.
UTC
UTC date and time: pairs of DATE and TIME tokens, DATE first.
STR
The data quantum is a bit combination ("character") and the
addressable range is viewed as a string. There is no
filtering or normalization. Addressing is always in terms of
complete bit combinations.
NODE
NODE LIST
The node or nodes to be compared to each other using the specified
comparison.
Purpose
Use Compare() to compare the members of a node list to each other
using a comparison. Comparisons are done in a way appropriate for the
quantum.
Examples
This simple example uses compare to confirm that the node list
returned by the query in the example for assign() is really made up
only of P elements. In this example, the HyQ query is contained
within a made-up element called TrueOrFalse. For the purpose of this
example, assume that the purpose of the TrueOrFalse element is to
contain a query that will return either TRUE or FALSE and that the
result of the query will be taken as the data of the TrueOrFalse
element. Note the Notation= attribute indicating that the data
contained by the TrueOrFalse element is a HyQ query.
<TrueorFalse notation=HyQ>
| and(
| assign(nlref(ElderSiblings) relloc(DOMTREE oo(an-element) esib (1 -1)))
| compare(EQ select(ElderSiblings EQ(proploc(CAND GI) "P"))
| )
<TrueorFalse>
------------------------------------------------------------------------------
create()
Create a node list
Syntax
<- -----------------<
>>---.--------.-(---.-| Node |------.---)---------------------------><
'-create-' '-| Node List |-'
NODE
Node List
The node or nodes making up the node list.
Purpose
Use the Create() function to create a node list, such as a list of
literal values. The function name can be omitted. This means that
any group of valid nodes will be interpreted as a node list when
surrounded by parentheses any place a node list is valid.
Examples
In this simple example, the create() function is used to create two
lists of literals for the diff() function. The second node list
demonstrates how the create name can be omitted:
<HyQ>
diff(CREATE("id-a" "id-b" "id-c") ("id-a" "id-c" "id-d"))
</HyQ>
------------------------------------------------------------------------------
dataloc()
Select data from nodes
Syntax
.- STR--. .- NOCATSRC-.
>>--dataloc(--| Node List |--+-------+--+-----------+---------------->
|- NORM-| '- CATSRC---'
|- WORD-|
|- NAME-|
|- SINT-|
|- DATE-|
|- TIME-|
'- UTC--'
.- NOCATRES-. .- ERROR--.
>--+-----------+--.-----------------------.--+---------+--)---------><
'- CATRES---' | <-----------------< | |- WRAP---|
'----| Marker Pair |----' |- TRUNC--|
'- IGNORE-'
MARKER PAIR:
|-- (signed_non-zero_integer signed_non-zero_integer)----------------|
NODE LIST
The list of nodes from which data will be selected.
QUANTUM
Represents the Quantum= attribute of the dataloc form. This value
defines what constitutes a quantum in the data. Valid values are:
NORM
Normalized text: all characters except record start (RS),
record end (RE), and separation characters (SEPCHAR), normally
space and tab.
WORD
Word tokens: all name characters.
NAME
SGML name: NAME constructed according to ISO 8879.
SINT
Signed integer: digit string, optionally preceded by a hyphen
or plus.
DATE
UTC date: valid date in UTC yyy-mm-dd format.
TIME
UTC time: valid time in UTC hh:mm:ss.decimal format.
UTC
UTC date and time: pairs of DATE and TIME tokens, DATE first.
STR
The data quantum is a bit combination ("character") and the
addressable range is viewed as a string. There is no
filtering or normalization. Addressing is always in terms of
complete bit combinations.
CATSRC
NOCATSRC
Concatenate source. Concatenates the objects of a multiple
location source into a single object before applying the dimension
list to it. The parsing context must be the same for all of the
objects.
Nocatsrc is the default.
CATRES
NOCATRES
Determines whether or not the result of the query should be
concatenated.
MARKER PAIR
One or more dimension marker pairs defining the location within
the objects being located.
OVERRUN
Overrun handling specification as defined in 10744 7.1.2.1. The
overrun handling determines what action to take in the event that
a dimension reference exceeds the size of the addressable range.
Valid values are:
ERROR
Treat the overrun as an error condition.
WRAP
Wrap around the range modulo the length of the range.
TRUNC
Truncate either to the first or last quantum of the range. If
either marker is before the first quantum, it is treated as
the first quantum. If either marker is after the last
quantum, it is treated as the last quantum.
IGNORE
Treat the dimension as though it had not been specified. This
may result in an error in some circumstances.
Purpose
Use dataloc() to locate data directly, rather than indirectly using
some abstraction of the data (such as node lists. See the entry for
listloc() for a discussion of the difference between dataloc() and
| listloc()). For example, you could use dataloc() to locate data
| within an ASCII text file or a string words within an SGML element.
(See 10744 8.4.1 for more information using data locations).
Examples
| This example locates a segment of sound data within a sound object.
| The returned sound data is used as the content of the Audio element
| for presentation purposes:
| <Audio notation=HyQ><!-- Returns data found with dataloc() -->
| dataloc(oo(asound) (10 1000)
| </Audio>
| The object-of function is used to define the location source for the
| query. The value 'asound' in this example is the ID of another
| element that refers to the actual audio data entity. The marker pair
| then locates that part of the sound starting at 10 and extending for
| 1000 quanta. This example uses the defaults for the quantum, catsrc,
catres, and overrun attributes.
This next example uses dataloc to address into the content of an
element. The quantum value 'WORD' is used, meaning that the data will
be divided into word quanta at each non-name character.
The target element is:
<phrase id=cats>Charles' and Linda's Abyssinians</phrase>
The query to find the second and third words is:
<NewPhrase notation=hyq>
dataloc(oo(cats) word (2 2))
</NewPhrase>
The object-of function makes the element with the ID 'cats' the
location source. The marker pair '2 2' locates the second and third
words (start at quantum 2 and extend for 2 quanta). The resolved
| content of the NewPhrase element is thus 'and Linda'.
------------------------------------------------------------------------------
diff()
Difference between nodelists
Syntax
<- -------------<
>>--diff(---| Node List |---)---------------------------------------><
NODE LIST
The node lists to be compared. The diff is applied by taking the
diff of the first two node lists, then taking the diff the result
with the next node list, and so on.
Purpose
Use Diff() to find the differences between two node lists.
Examples
In this simple example, two lists of literals are compared to find the
differences. In this example, the literals are element IDs.
<HyQ>
diff(("id-a" "id-b" "id-c") ("id-a" "id-c" "id-d"))
</HyQ>
| The result of the diff is 'id-b id-d'
------------------------------------------------------------------------------
forall()
Do all nodes meet assertion?
Syntax
>>--forall(-| Node List |- -| query() |-)---------------------------><
NODE LIST
The node list to apply the query against.
QUERY()
The query function that will be applied to each node in the node
list.
Purpose
Forall() returns TRUE if all nodes in a node list satisfy a query.
Examples
In this example, a proploc query is used to determine whether or not
all elements in the domain have an ID attribute value:
forall(DOMTREE query(proploc(DOMROOT ATTVAL[ID]))
The proploc() function returns the value of the ID attribute for the
candidate node. Because the proploc() function occurs where an
assertion is expected, it will resolve to TRUE if the property value
is not empty, FALSE if it is). The forall() function will return TRUE
if all the candidate nodes get a TRUE result from the query.
------------------------------------------------------------------------------
hylex()
Define a HyLex expression
Syntax
.- NORM--.
>>--hylex((HyLex specification)--+--------+--.-------------------.--->
'- UNORM-' '- OO(lexord_idref)-'
>--)----------------------------------------------------------------><
HyLex Specification
A pattern specification in the HyLex notation. HyLex is similar
to Unix regular expressions. See 10744 Annex A.1 for more
information about HyLex.
NORM
UNORM
Indicates whether or not the target strings are normalized as for
dataloc with the NORM option. The default is normalization.
OO(lexord_idref)
Refers to a lexical ordering (lexord) element that defines the
lexical ordering to be used for satisfying the HyLex pattern. The
default is to use the ordering of the active character set.
Purpose
Use HyLex() to define a HyLex pattern for use within a match()
function.
Examples
This example uses HyLex within match() to see the target elements
contain a US zip code:
<HyQ>
select(DOMTREE match(CAND HYLEX((digit, digit, digit, digit, digit,
("-",digit, digit, digit, digit)?)))
</HyQ>
------------------------------------------------------------------------------
inter()
Intersection of node lists
Syntax
<- -------------<
>>--inter(---| Node List |---)--------------------------------------><
NODE LISTS
The node lists to take the intersection of. The node list
returned contains the nodes common to all node lists specified.
Purpose
Use inter() to find common members in two node lists. This is useful
for combining different queries. For example, you might do one query
that returns a list of nodes containing a certain string and another
that returns a list matching a certain property. You can use inter()
to find the nodes common to both queries, thus finding the nodes with
the property that contain the string.
Examples
This query creates two node lists and then finds the intersection of
them:
<HyQ>
assign(PhraseList select(DOMTREE UseQ(HasGI "phrase")))
assign(ContainsAIX select(DOMTREE match(CAND "AIX")))
inter(nlref(PhraseList) nlref(ContainsAIX))
<!-- Return all phrases that contain AIX -->
</HyQ>
------------------------------------------------------------------------------
listloc()
Pick nodes from list by position
Syntax
>>--listloc(--| Node List |--.-----------------------.--------------->
| <-----------------< |
'----| Marker Pair |----'
.- ERROR--. .- NOSET-.
>--+---------+--+--------+--)---------------------------------------><
|- WRAP---| '- SET---'
|- TRUNC--|
'- IGNORE-'
MARKER PAIR:
|-- (signed_non-zero_integer signed_non-zero_integer)----------------|
NODE LIST
The node list from which nodes will be returned according to the
marker specifications.
MARKER PAIRS
One or more pairs of axis markers locating the nodes to be
returned.
OVERRUN
Overrun handling specification as defined in 10744 7.1.2.1. The
overrun handling determines what action to take in the event that
a dimension reference exceeds the size of the addressable range.
Valid values are:
ERROR
Treat the overrun as an error condition.
WRAP
Wrap around the range modulo the length of the range.
TRUNC
Truncate either to the first or last quantum of the range. If
either marker is before the first quantum, it is treated as
the first quantum. If either marker is after the last
quantum, it is treated as the last quantum.
IGNORE
Treat the dimension as though it had not been specified. This
may result in an error in some circumstances.
SET
NOSET
Determines whether or not a multiple location is treated as a set
by removing duplicates. The default is NOSET.
Purpose
Use listloc() to locate nodes within a node list. Listloc() is
essentially the same as a dataloc, but is restricted to a single
| dimension as node lists are always one dimensional. Listloc() is also
| distinquished from dataloc() by the type of quanta addressed.
| Dataloc() addresses bit combinations or tokens, while listloc()
| address nodes. Nodes are, by their nature, an abstraction of a given
| data notation, thus a node list is always the result of applying some
| sort of abstracting processing against data (e.g., parsing it with an
| SGML parser to find the element "nodes"). Note that any data type can
| be abstracted into a node list by applying some sort of parser to it.
| For example, raw video data could be addressed using dataloc, or it
| could be abstracted into a node list of "frames" by first applying a
| program that decoded the video data into frame chunks.
| Another way to think of the difference between listloc() and dataloc()
| is that while dataloc() operates on and returns the raw data,
| listloc() operates on and returns sets of pointers to data.
Examples
This example uses dataloc to return the content of a node as a node
list of words and then uses listloc to return the fourth through sixth
nodes in the resulting list:
<HyQ>
listloc(dataloc(oo(an-element) word (1 -1)) (4 3))
</HyQ>
| The example shows how dataloc() abstracts the raw data (words) into
| nodes, which can then be addressed as a node list by listloc().
------------------------------------------------------------------------------
match()
Pick nodes by pattern match of content
Syntax
>>--match(--.-| Node |------.--.- -| hylex() |----------------.------>
'-| Node List |-' |- qualified_lexical_type_name-|
'- literal---------------------'
.- ISCIEC--.
>--.-------------.--+----------+--.------------------------.--)-----><
'- OO(lexord)-' |- SODEOD--| '- minhits-.----------.--'
|- SODIEC--| '- maxhits-'
|- ISCEOD--|
'- INMODEL-'
NODE
NODE LIST
The node or node list against which the match is applied. When a
node list is specified, the match is applied against each node in
the list.
HYLEX()
qualified_lexical_type_name
LITERAL
The pattern to be matched against. Can be specified with the
HyLex() function, by giving the name of a qualified lexical type,
or by specifying a string literal.
OO(lexord_idref)
Refers to a lexical ordering (lexord) element that defines the
lexical ordering to be used for satisfying the HyLex pattern. The
default is to use the ordering of the active character set.
BOUNDARY CONSTRAINT
These keywords define the boundary constraints for the hits as
follows:
ISCIEC
Ignore starting characters, ignore ending characters.
Indicates that the hit can be anywhere within the match
domain. This is the default.
SODEOD
Match start of domain and end of domain. The hit must start
at the start of the domain and end at the end of it. For a
literal string, the hit must match the domain. For lexical
types or HyLex patterns, the entire domain must satisfy the
lexical constraints.
SODIEC
Match start of domain, ignore ending characters. The hit must
match the start of the domain.
ISCEOD
Ignore starting characters, match end of domain.
INMODEL
Indicates that the boundary constraints are defined in the
HyLex lexical model or the model for the referenced lexical
type.
minhits maxhits
Defines the hit range for the match, in other words the minimum
and, optionally, maximum number of hits needed to satisfy the
match.
Purpose
Use match to do patterning matching within a query. The pattern
matching mechanism can be one of the following:
o Simple string match, done by specifying a string literal, and
optionally, the boundary constraints.
o HyLex pattern matching using a HyLex lexical model as defined in
10744 Annex A.1., either by specifying the lexical model directly
with a HyLex() function or by defining a lexical type elsewhere
and specifying the lexical type name.
o A non-HyTime-defined pattern matching method using a pre-defined
lexical type name defined using an application-defined notation
(for example, grep regular expressions could be defined as a
notaton and used via defined lexical type names).
Examples
This example uses match() with a literal string and a boundary
constraint to find all phrase elements that start with the string
'AIX'.
<HyQ>
match(UseQ(HasGI "phrase") "AIX" SODIEC)
</HyQ>
------------------------------------------------------------------------------
nl
Nodelist-creating functions
Syntax
NL:
|--.-DOMTREE------.--------------------------------------------------|
|-DOMROOT------|
|-| assign() |-|
|-| nlref() |--|
|-| nlops() |--|
|-| nldefs() |-|
|-| oo() |-----|
'-| query() |--'
Purpose
Use nodelist-creating functions wherever a node list is valid. The
special keyword DOMTREE refers to all nodes rooted to the domain root.
The special keyword DOMROOT refers to the node list that is the root
of the domain.
------------------------------------------------------------------------------
nldefs
Nodelist-defining functions
Syntax
NL DEFS:
|--.-| proploc() |-.-------------------------------------------------|
|-| treeloc() |-|
|-| pathloc() |-|
|-| listloc() |-|
|-| dataloc() |-|
'-| relloc() |--'
Purpose
Nodelist-defining functions return a node list consisting of nodes
selected from the input node list.
------------------------------------------------------------------------------
nlops
Nodelist-manipulating functions
Syntax
NL OPS:
|--.-| select() |-.--------------------------------------------------|
|-| create() |-|
|-| union() |--|
|-| inter() |--|
'-| diff() |---'
Purpose
Node-list manipulating functions apply another function against the
members of the input node list, returning a new node list containing
those nodes from the input that satisfied the function.
------------------------------------------------------------------------------
nlref()
Resolves name to nodelist
Syntax
>>--nlref(nodelist_name)--------------------------------------------><
nodelist_name
The name of a node list previously created in the same query using
the assign() function.
Purpose
Lets you use a node list by reference.
Examples
In this example, assign() used to create two node list names, which
are then used by reference in the inter() function.
<HyQ>
assign(PhraseList select(DOMTREE UseQ(HasGI "phrase")))
assign(ContainsAIX select(DOMTREE match(CAND "AIX")))
inter(NLREF(PHRASELIST) nlref(ContainsAIX))
<!-- Return all phrases that contain AIX -->
</HyQ>
------------------------------------------------------------------------------
Node
Node specification methods
Syntax
NODE:
|--.-"literal data"---------.----------------------------------------|
|-CAND-------------------|
|-| Argument Reference |-|
|-| oo() |---------------|
'-| count() |------------'
"literal data"
A node list of literals, such as IDs or other tokens.
CAND
The current candidate node within the context of a select()
function.
ARGUMENT REFERENCE
Refers to a variable argument, e.g., %1, %2.
OO()
Object-of function. Returns the node list of nodes corresponding
the element or entity referred to in the body of oo(). When
unified entity and ID name spaces are not being used, an entity
can be referred by using a named location address that refers to
an entity.
COUNT()
Returns a single integer value representing the number of quanta
in an addressable range.
Purpose
Any of these node-specification methods are valid wherever a single
node or node list is valid.
------------------------------------------------------------------------------
not()
Test Boolean NOT
Syntax
>>--not(-| Assertion |-)--------------------------------------------><
ASSERTION
Any of the assertion methods defined under Assertion. All
assertion methods return either TRUE or FALSE.
Purpose
Returns TRUE if the assertion is FALSE, returns FALSE if the assertion
is TRUE.
Examples
This simple example always returns FALSE:
<HyQ>
not(assert(TRUE))
</HyQ>
------------------------------------------------------------------------------
oo()
Resolves IDREF to its object
Syntax
>>--oo(element_ID)--------------------------------------------------><
element_ID
Returns as a node the element or entity referred to by the
element_ID value. When unified ID and entity name spaces are not
used, oo() can refer to an entity by referring to a named location
address (nameloc) that then refers to an entity.
Purpose
Use object-of to refer directly to elements for the purpose of
defining the domain of a query. When the ID and entity name space is
unified, object-of can refer directly to a declared entity. When the
name spaces are not unified, entities can be refered to by using a
named location address (nameloc) element to refer to the entity and
then using object-of to refer to the nameloc element.
Examples
This example uses oo() to get an element to be the source for a
dataloc() query that returns the content of the object:
<HyQ>
dataloc(OO(AN-ELEMENT) word (1 -1))
</HyQ>
The next example shows how to refer to an entity by using nameloc to
create a location ladder that refers to an entity. The dataloc() then
addresses a portion of the graphic:
<!-- In document's DTD subset: -->
<!-- Define a graphic entity for later reference: -->
<!ENTITY an-entity SYSTEM "filename.ext" NDATA graphic >
.
.
.
<!-- In the document proper: -->
<nameloc id=entity-reference><nmlist entity>an-entity</nameloc>
<HyQ>
dataloc(OO(ENTITY-REFERENCE) str (10 256)(35 1556)
</HyQ>
------------------------------------------------------------------------------
or()
Test Boolean OR
Syntax
<---------------<
>>--or(---| Assertion |---)-----------------------------------------><
ASSERTION
Any of the assertion methods defined under Assertion. All
assertion methods return either TRUE or FALSE.
Purpose
OR returns TRUE if any of the assertions are TRUE, and FALSE if all of
them are false:
Examples
This example returns true if either attribute value matches the
specified values:
<HyQ>
select(DOMTREE OR(EQ(proploc(CAND ATTVAL[HWPLATFORM]) "PS/2")
EQ(proploc(CAND ATTVAL[SWPLATFORM]) "AIX")))
</HyQ>
------------------------------------------------------------------------------
ordered()
Tests if nodes are properly ordered
Syntax
| >>--ordered(--| Node List |--.-----------.--)-----------------------><
|-OVERLAP---|
'-NOOVERLAP-'
OVERLAP
NOOVERLAP
Indicates whether or not the nodes can overlap.
Purpose
Returns TRUE if all the nodes have the same additional property source
(apropsrc, see 10744 8.5.1: Property location address) and are ordered
within it. The additional property source is the common container for
all the nodes.
Examples
The following query returns TRUE:
<HyQ>
| ordered(('1' '2' '3' '4'))
</HyQ>
------------------------------------------------------------------------------
pathloc()
Pick nodes from tree by paths
Syntax
>>--pathloc(--| Node List |--.-----------------------.--------------->
| <-----------------< |
'----| Marker Pair |----'
.- NTREECOM-.
.- ERROR--. .- NOTSET-. |- TREECOM--|
>--+---------+--+---------+--'-----------'--)-----------------------><
|- WRAP---| '- SET----'
|- TRUNC--|
'- IGNORE-'
NODE LIST
The tree being addressed.
MARKER PAIRS
Two or more sets of marker pairs locating the path within the
tree.
OVERRUN
Overrun handling specification as defined in 10744 7.1.2.1. The
overrun handling determines what action to take in the event that
a dimension reference exceeds the size of the addressable range.
Valid values are:
ERROR
Treat the overrun as an error condition.
WRAP
Wrap around the range modulo the length of the range.
TRUNC
Truncate either to the first or last quantum of the range. If
either marker is before the first quantum, it is treated as
the first quantum. If either marker is after the last
quantum, it is treated as the last quantum.
IGNORE
Treat the dimension as though it had not been specified. This
may result in an error in some circumstances.
SET
NOTSET
Determines whether or not the result node list is treated as a set
by removing duplicates.
TREECOM
NTREECOM
Determines whether or not multiple source trees are combined. The
default is no combination.
Purpose
Pathloc locates into a tree as though it were a matrix where each
column consists of each node from the root to one leaf.
Examples
This query locates the path from the root to the second leaf of the
tree:
<HyQ>
pathloc(DOMTREE (2 1 1 -1))
</HyQ>
By using the SET parameter, you can remove the duplicates created by
locating more than one path:
<HyQ>
pathloc(DOMTREE (2 2 2 4) SET)
</HyQ>
------------------------------------------------------------------------------
proploc()
Returns value of a property
Syntax
>>--proploc(--.-| Node |------.-- qualified_property_name------------>
'-| Node List |-'
.- SEVERAL-. .- SOLESRC--. .- IGNORE-.
>--+----------+--+-----------+--+---------+--)----------------------><
'- JOINT---' '- APROPSRC-' |- ERROR--|
'- EMPTY--'
NODE
NODE LIST
The node or node list from which property values are to be
retrieved.
qualified_property_name
The name of the property to be retrieved. For SGML attributes,
this is simply the name of the attribute. The keyword 'GI'
returns the generic identifier of the element. Other properties
can be defined using HyTime property definitions (see 10744 6.7
Property sets and A.2 HyTime Property definition).
JOINT
SEVERAL
Determines whether or not the property applies to to all the nodes
in the source node list jointly or to each node individually. The
default is SEVERAL
SOLESRC
APROPSRC
Indicates whether or not to consider an additional property source
if the property is not applicable to the defined source.
IGNORE
EMPTY
ERROR
Determines the behavior in the case where the property is not a
property of the source node. When IGNORE is specified, the
proploc is treated as though it didn't exist. When EMPTY is
specified, an empty node is returned. When ERROR is specified it
is an error condition.
Purpose
Use proploc() to get the value of various properties of nodes, such as
the values of attributes of SGML elements. The value is returned as a
string literal.
| Examples
This query returns the value of the GI property of the source element:
<HyQ>
proploc(oo(an-element) GI)
</HyQ>
------------------------------------------------------------------------------
query()
specifies a query with args
Syntax
>>--query(--| Query Body |------------------------------------------->
>--.---------------------------------------.--)---------------------><
'-| Query Domain |--| Query Arguments |-'
QUERY BODY:
|--| Node List |-----------------------------------------------------|
QUERY DOMAIN:
.-DOMROOT-------.
|--+---------------+-------------------------------------------------|
'-| Node List |-'
QUERY ARGUMENTS:
<----------<
|----| Node |--------------------------------------------------------|
QUERY BODY
The query itself, defined using normal HyQ primitives.
QUERY DOMAIN
The domain against which the query is applied.
QUERY ARGUMENTS
Arguments to be passed to the query body as though specified on
the args= attribute of the HyQ element.
Purpose
Query() lets you define a query with replaceable arguments and then
call it directly, rather than indirectly via the UseQ function. The
difference between query() and UseQ() is that with UseQ() the function
body is refered to indirectly and may be defined elsewhere, while with
query(), the function body is defined within the query() function
itself.
Examples
This example defines a simple query with one argument and then uses
query() to apply it against the specified query domain, returning a
node list containing the value of the Security= attribute for each
node in DOMTREE:
query(proploc(%1 ATTVAL[SECURITY]) DOMTREE)
------------------------------------------------------------------------------
relloc()
Pick nodes from tree by relatives
Syntax
.- PARENT---.
>>--relloc(--| Node List |-- --.-| Node |------.--+-----------+------>
'-| Node List |-' |- ANC------|
|- ESIB-----|
|- YSIB-----|
|- DES------|
'- CHILDREN-'
.- ERROR--. .- NOTSET-.
>--.-----------------------.--+---------+--+---------+--)-----------><
| <-----------------< | |- WRAP---| '- SET----'
'----| Marker Pair |----' |- TRUNC--|
'- IGNORE-'
| NODE LIST
| The node or node list whose relatives are to be located.
| NODE | NODE LIST
| The root of tree within against which the relloc() is performed,
| normally, DOMROOT.
RELATION:
ANC
Ancestors of source.
ESIB
Elder siblings of source.
YSIB
Younger siblings of source.
DES
Descendants of source. Addressed as for pathloc().
PARENT
Parent of source. Equivalent of ANC with a dimlist of (-1 1).
Actual dimlist must be empty.
CHILDREN
Children of source. Equivalent of DES with a dimlist of (1 -1
2 1). Actual dimlist must be empty.
MARKER PAIRS
Sets of axis markers locating elements within the set of elements
identified by the relationship keyword. Cannot be specified for
PARENT or CHILDREN relationships.
OVERRUN
Overrun handling specification as defined in 10744 7.1.2.1. The
overrun handling determines what action to take in the event that
a dimension reference exceeds the size of the addressable range.
Valid values are:
ERROR
Treat the overrun as an error condition.
WRAP
Wrap around the range modulo the length of the range.
TRUNC
Truncate either to the first or last quantum of the range. If
either marker is before the first quantum, it is treated as
the first quantum. If either marker is after the last
quantum, it is treated as the last quantum.
IGNORE
Treat the dimension as though it had not been specified. This
may result in an error in some circumstances.
SET
NOTSET
Determines whether or not the result node list is treated as a set
by removing duplicates.
Purpose
Use relloc() to construct queries about nodes based on their
genealogical relationships to other nodes.
Examples
The following query locates the second path from the source node to
the the bottom of the tree:
<HyQ>
| relloc(oo(an-element) DOMROOT DES (2 1 1 -1))
</HyQ>
------------------------------------------------------------------------------
select()
Select nodes from list by assertion
Syntax
>>--select(--| Node List |-- --| Assertion |--)---------------------><
NODE LIST
The list of nodes from which the result node list will be
selected.
ASSERTION
Any of the assertion functions. The assertion is applied to each
node in the source node list, and any node for which the assertion
evaluates to TRUE will be returned in the result node list.
Purpose
Use select() to select nodes out of a node list.
Within the context of select(), the keyword CAND refers to the current
candidate node in source node list. When select() is nested within a
select, CAND refers to nodes in the node list of the innermost select
that contains the query using CAND.
If you need to use the value of an outer CAND within the body of a
nested select, you can use assign() to assign CAND to a symbolic name
and then use nlref() within the nested select to refer to the assigned
name.
Examples
This example selects from the domain tree all nodes whose GI is equal
to the value "partnum":
<HyQ>
select(DOMTREE EQ(proploc(CAND GI) "partnum"))
</HyQ>
In this example, assign() is used to capture the value of CAND for use
in a nested select. The query compares the value of the security=
attribute of containing Section elements with the security= value of
footnotes within the Section:
<HyQ>
Select(DOMTREE
and(Eq(Proploc(CAND GI) "SECTION")
ASSIGN(CURSECTION CAND)
Select(PATHLOC((CAND) 1 -1 2 -1)'
and(Eq(Proploc(CAND GI) "FOOTNOTE")
Le(Proploc(CAND ATTVAL[SECURITY])
Proploc(NLREF(CURSECTION)
ATTVAL[SECURITY])
)
)
)
</HyQ>
------------------------------------------------------------------------------
treeloc()
Pick nodes from tree by position
Syntax
<------------------------<
>>--treeloc(--| Node List |--- signed_non-zero_integer--------------->
.- NTREECOM-.
.- ERROR--. .- NOTSET-. |- TREECOM--|
>--+---------+--+---------+--'-----------'--)-----------------------><
|- WRAP---| '- SET----'
|- TRUNC--|
'- IGNORE-'
NODE LIST
The root node(s) of the tree to which the treeloc() applies.
SIGNED_NON-ZERO_INTEGERS
The number of each ancestor node at each level of the tree. Each
number is essentially a listloc of the form (x 1), locating a
single node in the node list of children of the previous node.
OVERRUN
Overrun handling specification as defined in 10744 7.1.2.1. The
overrun handling determines what action to take in the event that
a dimension reference exceeds the size of the addressable range.
Valid values are:
ERROR
Treat the overrun as an error condition.
WRAP
Wrap around the range modulo the length of the range.
TRUNC
Truncate either to the first or last quantum of the range. If
either marker is before the first quantum, it is treated as
the first quantum. If either marker is after the last
quantum, it is treated as the last quantum.
IGNORE
Treat the dimension as though it had not been specified. This
may result in an error in some circumstances.
SET
NOTSET
Determines whether or not the result node list is treated as a set
by removing duplicates.
TREECOM
NTREECOM
Determines whether or not multiple source trees are combined. The
default is no combination.
Purpose
Use treeloc() to locate single nodes within a tree. Treeloc() is a
very compact way to locate nodes within trees. For example, using the
sample tree shown under "Nodelist and Tree Addressing" on page i, the
tree location (3 2) locates the node labeled "I", while the tree
location (1 2 1) locates the node labeled "J".
Examples
The following example uses relloc() to locate the children of DOMROOT
and then uses treeloc() to find the first child of the second child of
each child of DOMROOT:
<HyQ>
treeloc(relloc(DOMROOT CHILDREN) 2 1 NTREECOM)
</HyQ>
The NTREECOM keyword states explicitly that for the node list returned
by relloc(), each node should be treated as the root of a separate
tree.
------------------------------------------------------------------------------
union()
Union of Node Lists
Syntax
<---------------<
>>--union(---| Node List |---)--------------------------------------><
NODE LISTS
The node lists to be combined.
Purpose
Takes two or more node lists and combines them into a single node
list, removing any duplicates.
Examples
This example uses two proploc() functions to create two node lists of
elements with specific GIs, and then uses union() to combine the two
lists into one:
<HyQ>
union(select(DOMTREE eq(proploc(CAND GI) "CAUTION"))
select(DOMTREE eq(proploc(CAND GI) "WARNING")))
</HyQ>
------------------------------------------------------------------------------
UseQ()
Indirect query
Syntax
>>--useq(--function_name--------------------------------------------->
>--.---------------------------------------.--)---------------------><
'-| Query Domain |--| Query Arguments |-'
QUERY DOMAIN:
.-DOMROOT-------.
|--+---------------+-------------------------------------------------|
'-| Node List |-'
QUERY ARGUMENTS:
<----------<
|----| Node |--------------------------------------------------------|
function-name
The name of a HyQ function defined elsewhere using the FN=
attribute of the HyQ element.
QUERY DOMAIN
The domain against which the named query is applied. The default
is DOMROOT.
QUERY ARGUMENTS
A node or node list containing the arguments to the named query.
Purpose
Use UseQ() to use pre-defined functions.
Examples
This example defines a new function, called Has_Attribute_Value, which
takes an attribute name and value and returns TRUE if the node's
attribute has the value. This function is then used in a subsequent
query.
<HyQ fn="Has_Attribute_Value">
<!-- Arguments: qdomain attname attvalue -->
EQ(proploc(%1 %2) %3)
</HyQ>
<!-- Now use this function in another query: -->
<HyQ>
select(DOMTREE USEQ(Has_Attribute_Value CAND ATTVAL[SECURITY] "IUO"))
</HyQ>
Footnotes:
| (1) The simplest application of multi-dimensional address is through of use of
| finite coordinate space location elements (fcsloc), which provide a
| mechanism for imposing a finite coordinate space onto an object for the
| purpose of then locating areas within the object. For example, one way to
| define hot spots within bitmap images would be to use fcsloc elements to
| define rectangular regions within the image.
| The other application of multi-dimentional addressing is to define the
| location of objects (called events) within a finite coordinate space using
| an indirection method called an event schedule The purpose of an event
| schedule is to associate objects with locations within a coordinate space of
| one or more dimensions. The subject of event schedules and finite
| coordinate spaces is beyond the scope of this document. For now, just
| remember that an extent list contains one set of dimension specifications (a
| dimlist) for each axis in the finite coordinate space.
(2) SGML documents can also be represented as one-dimensional coordinate spaces
with the quanta representing SGML elements in the order they are encountered
| (3) See section 6.7 Property Sets for the definition of HyTime's property set
| elements
(4) Note that the GI property is one of the standard properties and so the
property set name specification can be omitted, as it is in this example